Spateo-viewer: the “Google earth” of spatial transcriptomics
Jiajun Yao
Aristotle ecosystem team
https://github.com/aristoteleo/spateo-viewer
https://github.com/aristoteleo/spateo-release
Introduction
What is Spateo-viewer?
How does Spateo-viewer work?
Why Spateo-viewer?
Getting started
Documentation
Installation
Usage
Interactive-viewer
Build 2D/3D spatial transcriptomics models
Preprocess point cloud of single cells
Reconstruct 3D meshes of tissue or organs
Align serial slices of tissue or organs
……
Static-viewer
2D/3D Tissue visualization
Gene expression visualization
Morphogenesis calculation and visualization
Morphometric vector field animation
Morphometric measurements
Superior spatial transcriptomics models renderer
……
Outline (~30 mins)
Introduction
Introduction
What is Spateo-viewer?
Spateo-viewer is the “Google earth of spatial transcriptomics. Relying on a set of
powerful libraries and tools in the Python ecosystem, such as Trame, PyVista, VTK,
etc., it delivers a complete web application solution of creating convenient, vivid, and
lightweight interface for 3D reconstruction and visualization of Spateo downstream
analysis results. Currently, Spateo-viewer includes two major applications, interactive-
viewer and static-viewer, which are respectively dedicated to the 3D reconstruction of
spatial transcriptomics and the visualization of spatial transcriptomics analysis results.
How does Spateo-viewer work?
Spateo-viewer is a lightweight and completely self-contained web application based
on python, that can run either through a server or your local environment without
network connection, thereby ensuring that Spateo-viewer can be used for visualization
of spatial transcriptome data of any data size.
Introduction
Why Spateo-viewer?
Spateo-viewer is a lightweight network application with few dependent packages and easy
installation, which could be used in common systems such as Windows, Linux and MacOS.
Spateo-viewer helps researchers with limited python programming skills to build and
visualize 2D or 3D spatial transcriptomics models through an interactive web portal, and
even perform downstream analysis of spatial transcriptomics data such as predicting
organ morphogenesis trajectories.
Getting started
Documentation
https://github.com/aristoteleo/spateo-viewer
https://github.com/aristoteleo/spateo-viewer/blob/main/usage/StaticViewerUsage.md
https://github.com/aristoteleo/spateo-viewer/blob/main/usage/InteractiveViewerUsage.md
https://github.com/aristoteleo/spateo-release
https://spateo-release.readthedocs.io/en/latest/tutorials/notebooks/tdr.html
Installation
git clone https://github.com/aristoteleo/spateo-viewer.git
cd spateo-viewer
pip install -r requirements.txt
Usage
# Run Interactive-Viewer
python ./stv_interactive_app.py --port 1234
# Run Static-Viewer
python ./stv_static_app.py --port 1234
Getting started
Interactive-Viewer
2D/3D spatial transcriptomics
models generator
TOOLBAR
GUI
Useful widget for customizing
data upload
Active Model
Generate processed
2D/3D point cloud
model and its anndata
Slices Alignment
Realignment of serial
slices to build the 3D
point cloud model
Mesh
Reconstruction
Reconstruct the mesh
model based on the
3D point cloud model
DRAWER
GUI The logo of spateo-viewer
and the switch of drawer
Some useful widgets for
clipping active model:
Toggle mouse
function between
viewing model and
clipping model
Reset active model
to the original active
model
……
CONTAINER
GUI
Model could be translated, scaled, and rotated freely
Build 2D/3D spatial
transcriptomics models
Scalars: The key that stores information in `anndata.obs`.
ColorMap: Name of the matplotlib colormap to use when
mapping the scalars.
Pick Group: One or more subtypes can be extracted
from the original active model based on the information
contained in `Scalars`.
Overwrite the Active Model: If the `Overwrite the Active
Model` is on, multiple models can be extracted from the
original active model.
Active Model Output: File name of the active model. If
the file name ends with `vtk`, the active model will be
automatically saved to the `./stv_model` folder.
Anndata Output: File name of the anndata object. If the
file name ends with `h5ad`, the anndata object will be
automatically saved to the `./stv_model` folder.
Scalars: slices
ColorMap: Erdc Rainbow Bright
Pick Group: E8-10_b_S13
Overwrite the Active Model: False
Scalars: anno_tissue (Annotation)
ColorMap: Erdc Rainbow Bright
Pick Group: CNS and midgut
Overwrite the Active Model: True
Scalars: anno_tissue (Annotation)
ColorMap: Erdc Rainbow Bright
Pick Group: CNS
Overwrite the Active Model: False
2D spatial transcriptomics model
Multiple 3D spatial transcriptomics models
3D spatial transcriptomics model
Preprocess point cloud
of single cells
Clipping point cloud model to remove scattered points.
Saving clipped point
cloud model and its
anndata object.
Reset the active model to the initial model.
Scalars: anno_tissue (Annotation)
ColorMap: Erdc Rainbow Bright
Pick Group: None
Overwrite the Active Model: False
Scalars: The key that stores information in `anndata.obs`.
ColorMap: Name of the matplotlib colormap to use when
mapping the scalars.
Pick Group: If the key in Scalars that stores non-numeric
information, the Pick Group includes all categories.
Overwrite the Active Model: If the `Overwrite the Active
Model` is on, multiple models can be visualized simultaneously.
Active Model Output: File name of the active model. If the
file name ends with `vtk`, the active model will be
automatically saved to the `./stv_model` folder.
Anndata Output: File name of the anndata object. If the file
name ends with `h5ad`, the anndata object will be
automatically saved to the `./stv_model` folder.
Scalars: anno_tissue (Annotation)
ColorMap: Erdc Rainbow Bright
Pick Group: CNS
Overwrite the Active Model: False
Scalars: anno_tissue (Annotation)
ColorMap: Erdc Rainbow Bright
Pick Group: CNS
Overwrite the Active Model: False
Mesh reconstruction
Reconstruct Mesh Model: Open mesh reconstruction.
Clip with Mesh Model: Clipping active model with mesh model.
MC Factor: The most critical hyperparameter in the reconstruction method in the range of 0to 2.
Voronoi Clustering: Number of Voronoi clustering.
Smooth Factor: Number of iterations for Laplacian smoothing.
Scale Factor: The scale by which the model is scaled.
Reconstructed Mesh Output: File name of mesh model. If the file name ends with `vtk`, the
mesh model will be automatically saved to the `./stv_model` folder.
Mesh reconstruction. Clipping active model with mesh model.
Saving mesh model.
Slices alignment
Align slices: If the `Align slices` is on, re-align the slices in the atcive model.
Method of Alignment: The method used to realign the series slices. Currently we support Paste1, Morpho2.
Slices Key: The key in `anndata.obs` that corresponds to the slice names.
Align Factor: The most critical hyperparameter in the alignment method.
If the alignment method is Paste, it represents alpha, which is the Alignment tuning parameter. When
``alpha = 0`` only the gene expression data is taken into account, while when ``alpha =1`` only the
spatial coordinates are taken into account. Recommended setting from 0.01 to 0.1.
if the alignment method is Morpho, it represents max_outlier_variance. Reduce the spatial variance to
decrease Gaussian tails to achieve robustness to partial alignment. Lower means less robust, but more
accurate. Recommended setting from 1 to 50.
Max Iterations: The maximum number of iterations for alignment.
Device: Equipment used to run the program.
Slices Realignment
1. Zeira, R., Land, M., Strzalkowski, A. et al. Alignment and integration
of spatial transcriptomics data. Nat Methods 19, 567575 (2022).
2. Qiu, X. et al. Spateo: multidimensional spatiotemporal modeling of
single-cell spatial transcriptomics. BioRxiv 2022.12.07.519417 (2022).
Static-viewer
Superior spatial transcriptomics
models renderer
TOOLBAR
GUI
Useful widget for customizing
data upload
GitTree
Toggle active model
and model visibility
ModelCard
Optimize model
visualization or
calculate model
morphogenesis
OutputCard
Output screenshot
or animation
DRAWER
GUI The logo of spateo-viewer
and the switch of drawer
Some useful widgets:
Theme toggle
Background toggle
Rendering mode
toggle
Main model Visibility
toggle
Bounding box toggle
Ruler toggle
Axis toggle
Camera angles reset
……
CONTAINER
GUI
Model could be translated, scaled, and rotated freely
Gene expression visualization
Scalars: Name of the gene to be visualized.
Add Legend: Add the legend corresponding to the
current `Scalars` in the GUI.
Coords: Model coordinate name. `spatial` represents
the spatial coordinates in the reality, and `umap`
represents the spatial coordinates in the umap
dimensionality reduction space.
Matrices: Toggle gene expression matrices, including
all matrices contained in anndata.
Colormap: Name of the matplotlib colormap to use
when mapping the `Scalars` .
Opacity: Opacity of the model in the range of 0to 1.
Ambient: The amount of light in the range of 0to 1.
Point Size: Point size of any nodes in the dataset
plotted in the range of 0to 20.
Scalars: Bacc
Coords: spatial
Matrices: X_log1p
Colormap: default_cmap
Scalars: Bacc
Coords: spatial
Matrices: X_log1p
Colormap: magma
Users can conveniently choose genes to be visualized in the whole embryo model or in any one or more tissues.
Scalars: Bacc
Coords: umap
Matrices: X_log1p
Colormap: default_cmap
PC ModelCard
Tissues visualization
Scalars: None or the annotation key in the anndata.obs.
Picking Group: One or more subtypes can be extracted from the original active
model based on the information contained in `Scalars`.
Add Group: If the `Add Group` is on, multiple models can be extracted from the
original active model.
Reload Model: Reset the active model to the original active model.
Color: The color of the active model if `Scalars` is None.
Colormap: Name of the matplotlib colormap to use when mapping the `Scalars`.
Style: Visualization style of the model, including `points`, `surface` and `wireframe`.
Opacity: Opacity of the model in the range of 0to 1.
Ambient: The amount of light in the range of 0to 1.
Visibility: CNS PC and Mesh, Midgut PC and Mesh,
Embryo Mesh
Visibility: Embryo PC
Scalars: anno_tissue
Picking Group: CNS, Midgut, Salivary gland
Users can conveniently choose tissue models to be visualized.
Toggle active model
and model visibility PC ModelCard Mesh ModelCard
Morphogenesis visualization
Users can calculate the morphogenesis and visualize the morphometrics features.
Midgut with trajectory
Scalars: tsr (gene)
Color: default_cmap
Calculate the Morphogenesis: If `Target Anndata` is not
None, calculate the morphogenesis of the active model.
Uploaded Target Anndata: Upload the spatial
transcriptomics data of the next stage corresponding to
the active model.
Target Anndata: Select the next stage data for
calculating morphogenesis.
Morphofield Visibility: Toggle Morphofield visibility.
Morphopath Visibility: Toggle Morphopath visibility.
Midgut with vecterfield
Scalars: torsion (morphometrics feature)
Color: default_cmap
Morphometrics features:
1. acceleration: the time derivative of the velocity;
2. torsion: the degree of twisting;
3. curl: a quantity measuring the degree of rotation at
a given point in the morphometric vector field;
4. curvature: the derivative of the unit tangent vector;
5. Each of them have real physical meanings.
Morphogenesis visualization
Users can calculate the morphogenesis and visualize the morphometrics features.
Morphogenesis Animation Output: File
name of Animation. If the file name ends with
`mp4`, the animation will be automatically
saved to the `./stv_image` folder.
Midgut with trajectory
Scalars: torsion (morphometrics feature)
Color: default_cmap
Morphometric measurements
Ruler visible
Reset camera Y
Users can measure the morphological feature such as length, surface area and volume of the reconstructed 3D model of organ/embryo.
Ruler visible
Reset camera X
Ruler visible
Reset camera Z
Toggle ruler
Reset camera X
Toggle ruler
Reset camera Y
Toggle ruler
Reset camera Z
Only for mesh model
Image or animation generation/saving
Screenshot Output: File name of Screenshot. If the file name ends with `png` or `pdf`, the
image will be automatically saved to the `./stv_image` folder.
Animation N Points: Number of points on the orbital path in the animation.
Animation Framerate: Frames per second in the animation.
Animation Output: File name of Animation. If the file name ends with `mp4`, the animation will
be automatically saved to the `./stv_image` folder.
Screenshot Animation
Questions / Discussions
https://github.com/aristoteleo/spateo-viewer/issues
yaojiajun2021@gmail.com